Add Hydra micropayments (gateway↔end user) by michalrus · Pull Request #451 · blockfrost/blockfrost-platform

michalrus · 2026-02-09T21:58:29Z

Resolves #278

Context

Follow-up to: Add Hydra micropayments (gateway↔platform) #425 – please review that one first!
Here's the 2nd video to aid in review: 2026-02-20-blockfrost-hydra-demo-part-2.mp4

cloudflare-workers-and-pages · 2026-02-09T22:32:05Z

Deploying blockfrost-platform with Cloudflare Pages

Latest commit:	`42da948`
Status:	✅ Deploy successful!
Preview URL:	https://12949fa4.blockfrost-platform.pages.dev
Branch Preview URL:	https://feat-hydra-payments-2.blockfrost-platform.pages.dev

View logs

…23c005' git-subtree-dir: crates/gateway git-subtree-mainline: c6cad31 git-subtree-split: 35a134b

…refactor later)

…edits

Copilot

Pull request overview

Adds an SDK Bridge (local HTTP proxy ↔ Gateway WebSocket) and a new Hydra micropayment channel flow between Gateway and end user, alongside Gateway-side WebSocket support for the bridge and Hydra session management.

Changes:

Introduces new crates/sdk_bridge binary that proxies local HTTP requests to the Gateway over /sdk/ws and runs a local hydra-node to pay per request.
Adds a new Gateway /sdk/ws WebSocket route plus hydra_server_bridge to manage customer Hydra controllers and credit tracking.
Refactors Nix devshell Hydra scripts TX-id env var setup to use a shared internal helper.

Reviewed changes

Copilot reviewed 20 out of 21 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
nix/devshells.nix	Uses `internal.hydraScriptsEnvVars` to populate Hydra scripts TX-id env vars.
crates/sdk_bridge/Cargo.toml	New SDK bridge crate dependencies and lint config.
crates/sdk_bridge/src/main.rs	New bridge binary entrypoint wiring config, WS client, and HTTP proxy.
crates/sdk_bridge/src/config.rs	CLI args + normalization of Gateway WS URL.
crates/sdk_bridge/src/http_proxy.rs	Local Axum HTTP server that converts HTTP↔JSON-over-WS and enforces prepaid credits.
crates/sdk_bridge/src/ws_client.rs	WS connection loop to Gateway, request/response correlation, pinging, and hydra KEx/tunnel forwarding.
crates/sdk_bridge/src/hydra_client/mod.rs	Bridge-side Hydra controller: ceremony, commit, prepay, microtransactions, credit polling.
crates/sdk_bridge/src/hydra_client/verifications.rs	Bridge-side Cardano/Hydra verification helpers and subprocess utilities.
crates/sdk_bridge/src/protocol.rs	Shared JSON protocol types for bridge↔gateway messages.
crates/sdk_bridge/src/types.rs	Network enum + magic numbers used by hydra/cardano-cli invocations.
crates/sdk_bridge/src/find_libexec.rs	Helper to locate `hydra-node` / `cardano-cli` binaries.
crates/gateway/src/main.rs	Registers `/sdk/ws` route and initializes `hydra_bridge` manager.
crates/gateway/src/lib.rs	Exposes new `hydra_server_bridge` and `sdk_bridge_ws` modules.
crates/gateway/src/sdk_bridge_ws.rs	Implements Gateway-side bridge WebSocket server + in-memory HTTP dispatch and hydra credit gating.
crates/gateway/src/hydra_server_bridge/mod.rs	Gateway-side Hydra manager/controller for bridge customers, incl. KEx and credit monitoring/fanout.
crates/gateway/src/hydra_server_bridge/verifications.rs	Gateway-side Cardano/Hydra helpers used by bridge customer controllers.
crates/gateway/src/config.rs	Adds `[hydra_bridge]` configuration section to gateway config model.
crates/gateway/config/development.toml	Adds sample `[hydra_bridge]` config alongside existing `[hydra_platform]`.
crates/gateway/Cargo.toml	Adds `tower` dependency for `ServiceExt::oneshot` usage.
Cargo.toml	Adds `crates/sdk_bridge` to workspace members.
Cargo.lock	Locks new crate and dependency additions (notably `tower`).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

crates/sdk_bridge/src/hydra_client/mod.rs

+        let config_dir = dirs::config_dir()
+            .expect("Could not determine config directory")
+            .join("blockfrost-sdk-bridge")
+            .join("hydra")
+            .join(config.network.as_str())
+            .join("_default");


crates/sdk_bridge/src/http_proxy.rs

+    if (200..400).contains(&response.code) {
+        state.bridge.hydra().account_one_request().await;
+    }


crates/gateway/src/sdk_bridge_ws.rs

+            JsonResponse {
+                id: request_id_,
+                code: code.into(),
+                header: vec![],
+                body_base64: err,


crates/sdk_bridge/src/ws_client.rs

+fn error_response(request_id: RequestId, code: u16, msg: String) -> JsonResponse {
+    JsonResponse {
+        id: request_id,
+        code,
+        header: vec![],
+        body_base64: msg,
+    }


crates/gateway/src/sdk_bridge_ws.rs

+            while let Some(Ok(msg)) = sock_rx.next().await {
+                match msg {
+                    Message::Text(text) => {
+                        match serde_json::from_str::<BridgeMessage>(&text) {
+                            Ok(msg) => {
+                                if event_tx
+                                    .send(BridgeEvent::NewBridgeMessage(msg))
+                                    .await
+                                    .is_err()
+                                {
+                                    break;
+                                }
+                            },
+                            Err(err) => warn!(
+                                "sdk-bridge-ws: received unparsable text message: {:?}: {:?}",
+                                text, err,
+                            ),
+                        };
+                    },
+                    Message::Binary(bin) => {
+                        warn!(
+                            "sdk-bridge-ws: received unexpected binary message: {:?}",
+                            hex::encode(bin),
+                        );
+                    },
+                    Message::Close(frame) => {
+                        warn!(
+                            "sdk-bridge-ws: bridge disconnected (CloseFrame: {:?})",
+                            frame,
+                        );
+                        let _ignored_failure: Result<_, _> = event_tx
+                            .send(BridgeEvent::Finish("bridge disconnected".to_string()))
+                            .await;
+                        break;
+                    },
+                    Message::Ping(_) | Message::Pong(_) => {},
+                }
+            }


crates/gateway/src/hydra_server_bridge/mod.rs

+        let minimal_commit: f64 = 1.01
+            * (config.lovelace_per_request
+                * config.requests_per_microtransaction
+                * config.microtransactions_per_fanout
+                + MIN_LOVELACE_PER_TRANSACTION) as f64
+            / 1_000_000.0;
+        if config.commit_ada < minimal_commit {
+            Err(anyhow!(
+                "hydras-manager: Please make sure that configured commit_ada ≥ lovelace_per_request * requests_per_microtransaction * microtransactions_per_fanout + {}.",
+                MIN_LOVELACE_PER_TRANSACTION as f64 / 1_000_000.0
+            ))?
+        }
+
+        let microtransaction_lovelace: u64 =
+            config.lovelace_per_request * config.requests_per_microtransaction;
+        if microtransaction_lovelace < MIN_LOVELACE_PER_TRANSACTION {


crates/sdk_bridge/src/ws_client.rs

+    // Schedule the first `PingTick` immediately, otherwise we won’t start
+    // checking for ping timeout:


crates/sdk_bridge/src/ws_client.rs

+            BridgeEvent::NewRequest(req) => {
+                let request_id = req.request.id.clone();
+                inflight
+                    .lock()
+                    .await
+                    .insert(request_id.clone(), req.respond_to);
+                if let Err(err) =
+                    send_json_msg(&socket_tx, &BridgeMessage::Request(req.request)).await
+                {
+                    loop_error = Err(err);
+                    break 'event_loop;
+                }


crates/sdk_bridge/src/find_libexec.rs

+    // This is the most important one for relocatable directories (that keep the initial
+    // structure) on Windows, Linux, macOS:
+    let current_exe_dir: Option<PathBuf> =
+        std::fs::canonicalize(env::current_exe().map_err(|e| e.to_string())?)
+            .map_err(|e| e.to_string())?
+            .parent()
+            .map(|a| a.to_path_buf().join(exe_name));
+
+    // Similar, but accounts for the `nix-bundle-exe` structure on Linux:
+    let current_package_dir: Option<PathBuf> = current_exe_dir
+        .clone()
+        .and_then(|a| a.parent().map(PathBuf::from))
+        .and_then(|a| a.parent().map(PathBuf::from));
+
+    let cargo_target_dir: Option<PathBuf> = env::var("CARGO_MANIFEST_DIR")
+        .ok()
+        .map(|root| PathBuf::from(root).join("target/testgen-hs/extracted/testgen-hs"));
+
+    let docker_path: Option<PathBuf> = Some(PathBuf::from(format!("/app/{exe_name}")));


crates/gateway/src/sdk_bridge_ws.rs

+    fn error_response(request_id: RequestId, code: StatusCode, why: String) -> JsonResponse {
+        JsonResponse {
+            id: request_id,
+            code: code.as_u16(),
+            header: vec![],
+            body_base64: why,
+        }


ginnun

General nitpicking:
Significant code duplication between gateway and bridge — verifications.rs, find_libexec.rs, KeyExchangeRequest/KeyExchangeResponse, and JsonRequest/JsonResponse protocol types are all duplicated nearly verbatim. Any drift would cause silent wire-format incompatibilities. Consider DRY if preferred by you and possible.

Personally 3 or more repetitions is trigger for DRY.

ginnun · 2026-03-18T12:19:16Z

crates/gateway/src/hydra_server_bridge/mod.rs

+    WaitForIdleAfterClose,
+}
+
+fn mk_config_dir(network: &Network, customer_machine_id: &str) -> Result<PathBuf> {


Hmmm, is this dangerous? What happens if my payload is:

HydraKExRequest: { machine_id: "../../../../tmp/pwned-by-path-traversal", platform_cardano_vkey: {}, platform_hydra_vkey: {}, accepted_platform_h2h_port: null, },

If a valid scenario, we should validate machine_id to contain only hex chars.

ginnun · 2026-03-18T12:29:09Z

crates/gateway/src/main.rs


+    let sdk_state = sdk_bridge_ws::SdkBridgeState::new(base_router.clone(), hydras_bridge_manager);
+
+    let app = base_router


The /sdk/ws WebSocket endpoint has no authentication — any client can connect and start consuming Hydra resources (key exchange, hydra-node spawning).

Do sdk/ws need auth? Is authentication planned for a follow-up, or intentionally deferred?

ginnun · 2026-03-18T12:34:06Z

crates/sdk_bridge/src/ws_client.rs

+    Pong(u64),
+}
+
+async fn run_ws_loop(


If the WebSocket connection fails or drops, run_ws_loop exits permanently with no reconnection logic. The bridge's HTTP proxy stays alive but returns 503 for every subsequent request — a dead endpoint with no recovery path.

For inflight requests, the cleanup at the end of run_ws_loop correctly sends 503 via error_response. But no new connections are attempted.

ginnun · 2026-03-18T12:39:50Z

crates/gateway/src/sdk_bridge_ws.rs

+                        already_exists,
+                        &state.hydras,
+                        &req.accepted_platform_h2h_port,
+                        initial_hydra_kex.take(),


Nitpicking:
.take() is evaluated eagerly before the match arms, so the KEx state would be consumed even if an error arm were reached. In the current code this is harmless. The error arms can't fire when initial_hydra_kex is Some — but moving .take() inside the arm that binds initial_kex would be more robust against future refactors.

…opayments

… drop the `cardano-cli` requirement

michalrus self-assigned this Feb 9, 2026

michalrus added the enhancement New feature or request label Feb 9, 2026

This was referenced Feb 9, 2026

Hopper: Hydra payment channel between gateway and consumer #278

Open

Add POST /utils/txs/evaluate – how many execution units for a transaction #306

Open

michalrus force-pushed the feat/hydra-payments-2 branch 2 times, most recently from daa80bd to 9717d49 Compare February 18, 2026 14:43

michalrus added 12 commits February 18, 2026 20:38

Add 'crates/gateway/' from commit '35a134bc4f91d510c6f23ab93e9c4bfa99…

280ad00

…23c005' git-subtree-dir: crates/gateway git-subtree-mainline: c6cad31 git-subtree-split: 35a134b

chore: make crates/gateway a proper package in this workspace

367aa18

chore: get rid of +spec-1.1.0 from toml

42aeff4

chore: fix Clippy issues

3379005

chore: rename the hydra modules according to function

64b41f5

chore: remove unused tunnel.rs

42af219

chore: rename TOML’s hydra → hydra_platform

5c6d8bd

feat: re-do the initial version in separate files for clarity (we'll …

5f2a88d

…refactor later)

fix: the minimal top-up bug in the Bridge

09d681e

fix: get rid of the dust causing BabbageOutputTooSmallUTxO

5dc07a1

fix: allow Bridge request with non-Open head, as long as there are cr…

b73e9ac

…edits

chore: edit the default Bridge port for the videos

9403975

michalrus force-pushed the feat/hydra-payments-2 branch from e057bc7 to 9403975 Compare February 19, 2026 22:11

chore: using 3 µtransactions/fanout looks better

473bb17

michalrus force-pushed the feat/hydra-payments-2 branch from 9393aee to 473bb17 Compare February 19, 2026 23:22

michalrus added 4 commits February 21, 2026 16:36

fix(ci): try to fix the macOS build (missing libpq)

88b450d

fix(ci): try to fix the macOS build (missing libpq), take 2…

bd85832

fix: Nix archives

639c3df

fix(build): Windows

e394f56

michalrus force-pushed the feat/hydra-payments-2 branch from 98adc65 to e394f56 Compare February 23, 2026 09:21

This was referenced Feb 23, 2026

Tx evaluation #378

Open

Add blockfrost-gateway to this monorepo #464

Merged

Merge branch 'feat/hydra-payments' into feat/hydra-payments-2

f5665c2

michalrus force-pushed the feat/hydra-payments-2 branch from 366d717 to f5665c2 Compare March 13, 2026 14:01

michalrus changed the base branch from main to feat/hydra-payments March 13, 2026 14:02

michalrus requested review from ginnun and vladimirvolek March 13, 2026 14:04

michalrus mentioned this pull request Mar 13, 2026

Add Hydra micropayments (gateway↔platform) #425

Open

vladimirvolek requested a review from Copilot March 13, 2026 14:55

Copilot started reviewing on behalf of vladimirvolek March 13, 2026 14:56 View session

Copilot AI reviewed Mar 13, 2026

View reviewed changes

michalrus added 4 commits March 13, 2026 20:05

chore: add blockfrost-sdk-bridge to Nix packages

1bffe03

chore: relax coverage %

7a5aa6c

fix: anonymize node.socket and key paths

92c0e63

Merge branch 'feat/hydra-payments' into feat/hydra-payments-2

96bea9f

ginnun requested changes Mar 18, 2026

View reviewed changes

michalrus added this to the v1 milestone Mar 24, 2026

michalrus mentioned this pull request Mar 31, 2026

fix(hydra): test flakiness: OutsideValidityIntervalUTxO #502

Merged

michalrus added 9 commits April 2, 2026 10:23

Merge branch 'feat/hydra-payments' into feat/hydra-payments-2

c528c41

feat(hydra): add an integration test: SDK Bridge + Gateway Hydra micr…

28f23b8

…opayments

chore(hydra): add the new test to CI

8eeca71

fix(test): only ever exit with 0 if test_passed == true

31af299

Merge branch 'feat/hydra-payments' into feat/hydra-payments-2

2504d14

Merge branch 'feat/hydra-payments' into feat/hydra-payments-2

1b5eeb1

chore: drop the tracing prefixes in accordance with #501

f3b7fa4

feat(hydra): use hydra-node --blockfrost on the Gateway and Bridge;…

fffa6ee

… drop the `cardano-cli` requirement

fix(hydra): add timeout to send_one_websocket_msg – it sometimes hangs

42da948

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add Hydra micropayments (gateway↔end user)#451

Add Hydra micropayments (gateway↔end user)#451
michalrus wants to merge 31 commits intofeat/hydra-paymentsfrom
feat/hydra-payments-2

michalrus commented Feb 9, 2026 •

edited

Loading

Uh oh!

cloudflare-workers-and-pages bot commented Feb 9, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

ginnun left a comment

Uh oh!

ginnun Mar 18, 2026

Uh oh!

ginnun Mar 18, 2026

Uh oh!

ginnun Mar 18, 2026

Uh oh!

ginnun Mar 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		// Schedule the first `PingTick` immediately, otherwise we won’t start
		// checking for ping timeout:


		let sdk_state = sdk_bridge_ws::SdkBridgeState::new(base_router.clone(), hydras_bridge_manager);

		let app = base_router

Conversation

michalrus commented Feb 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Context

Uh oh!

cloudflare-workers-and-pages bot commented Feb 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying blockfrost-platform with Cloudflare Pages

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

ginnun left a comment

Choose a reason for hiding this comment

Uh oh!

ginnun Mar 18, 2026

Choose a reason for hiding this comment

Uh oh!

ginnun Mar 18, 2026

Choose a reason for hiding this comment

Uh oh!

ginnun Mar 18, 2026

Choose a reason for hiding this comment

Uh oh!

ginnun Mar 18, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

michalrus commented Feb 9, 2026 •

edited

Loading

cloudflare-workers-and-pages bot commented Feb 9, 2026 •

edited

Loading